-
Notifications
You must be signed in to change notification settings - Fork 351
Add Reference Popovers #1025
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Reference Popovers #1025
Conversation
Just wanted to say this is amazing. Couple minor points: (http://krowinski.com/ex_doc/popovers_done/elixir/GenServer.html#module-example) This is unfortunate result of security considerations above, we rightfully so don't interpret any markup and so we can't do indentation, new lines etc. What if for each spec DOM element we store a data attribute with spec in plaintext (with spaces and newlines) and use that to render in popover? This would obviously increase the size of the docs unfortunately. What do you think about making it possible to hover over content of the popover? (Currently it's not possible.) This way we'd be able to copy-paste stuff, e.g. complicated specs. Right now what we can do is click on the link and copy-paste the contents from the page we land on. Both issues are minor and if anything we should work on them in future PRs. |
This is awesome! ❤️ Here are some general comments:
|
expect(extractModuleHint(modulePageObject).kind).to.eql('module') | ||
}) | ||
|
||
it('extracts plain text, without html tags', () => { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this can be removed? :D
assets/js/tooltips/tooltips.js
Outdated
} | ||
// Tooltip will appear only if the mouse cursor stays on the link for at least 150ms. | ||
// This way tooltips will not appear if we are scrooling the page or just moving the cursor around. | ||
const hoverDelayTime = 150 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Because there is a loading time, I think we should be fine with 100 here. :D (bike shedding)
Thanks @wojtekmach , @josevalim !
Actually adding newline support should be super easy - I'm not removing inner whitespaces, just html tags. A
👍 I'll need to experiment with it a little bit. This I would definitely move to another PR, since it requires a bit of tinkering to get right :)
Personally I would vote for disabling them. At first I thought that, if I'm a newbie, a quick summary of the current module can still be useful. But after checking again I can see that current module is referenced mostly at the very top of the page, in the first description block - and popover does not make much sense there.
On it!
I wanted to see what I can do with types, but I feel that simpler tip might indeed be better.
👍I'll experiment with the styles/positioning and prepare a demo. |
I would also vote for disabling them, they get excessive quite fast in modules that reference lots of their own types/functions.
I like this. |
assets/js/tooltips/hints-page.js
Outdated
pathnameEnd: '/typespecs.html', | ||
categories: [ | ||
{ name: 'basicType', description: 'Basic type', hash: '#basic-types', detailsAvailable: false }, | ||
{ name: 'literal', description: 'Literal', hash: '#literals', detailsAvailable: false }, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think ExDoc doesn't link typespec literals, do you have any examples of this tooltip showing? 🙂
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think ExDoc doesn't link typespec literals, do you have any examples of this tooltip showing? 🙂
Ah, that makes sense! I've not seen them anywhere, but added this category just in case, but I guess I can safely remove it. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Given that the plan is to remove the typespec handling anyway, we don't have to worry about this particular bit either. :D
I've just uploaded the updates and fixes :) ➡️ Changelog:1. Removed type extraction for
|
Absolutely beautiful! ❤️ 💚 💙 💛 💜 |
I think I have found two, hopefully tiny, bugs:
|
For
Edit: The same also applies to |
Thanks for the info - should be a quick fix! :) |
Co-Authored-By: Wojtek Mach <wojtekmach@users.noreply.github.com>
Co-Authored-By: Wojtek Mach <wojtekmach@users.noreply.github.com>
I've fixed both reported issues :) ➡️ New demo: Demo Link (new one in next post)
Exactly - I missed the fact that we create separate anchors for that. Now it's fixed. :)
Sounds good, but that was not necessary - they are always direct descendants of the
|
❤️ 💚 💙 💛 💜 |
This looks cool! I have one idea though: wouldn't it be more useful if the displayed version was the |
Thanks @michallepicki Version info was added because tooltips work across projects (provided that both projects use the latest ex_doc version). I think |
@archdragon one option is: if since is available, we show "since Elixir v1.8.0", otherwise we show "seen on Elixir v1.8.0" or similar. WDYT? |
@archdragon cool, where can I see it in action? Here hovering over ExUnit.DocTest doesn't do anything for me: https://hexdocs.pm/elixir/master/writing-documentation.html#doctests , similarily here Logger stuff: https://hexdocs.pm/elixir/master/library-guidelines.html#avoid-macros |
@archdragon I just re-read your response and realized - both need to use latest ex_doc, understood |
the reason is ExUnit.DocTest link goes to https://hexdocs.pm/ex_unit/ExUnit.DocTest.html (which was generated with older ex_doc version). You can see it in action here: https://hexdocs.pm/elixir/master/Kernel.html as long as you hover over something that stays within Elixir docs (and not e.g. Mix) |
Makes sense! I'll need to spend just a bit more time on it to make sure it looks good. With |
@archdragon one option is to do this: "Elixir v1.8.0" (without since) and "Elixir v1.3.0+" (with since). |
Add reference popovers
Summary
Adds popovers discussed in: #971 - tooltips with extra info that appear after hovering over a link, Wikipedia style. :)
Demo
Demo Link (After fixes)
[ Old Demo Link ]1. What triggers a reference popover
Reference popover will appear after you hover over a:
➡️ Link to a function/callback - function signature and summary will be displayed

➡️Module - module name and summary will be displayed

➡️Types
➡️If defined in the module - name and signature will be displayed

➡️If defined on the typespecs page
➡️For built-in types - popover will extract detailed info

➡️For basic types and literals - basic hint will be displayed

2. Handling types
I'm able to show info about the built-in types, because they are displayed as a neat table - so it's easy to find the requested type and the corresponding definition.
For basic types and literals this is not really possible - their definitions are unstructured and displayed as one big
<code>
block.Maybe we could display them in a table instead? Then I'll be able to upgrade popovers descriptions. :)
3. Handling external links
External links - communication between different domains/projects - is fully supported.
For example if https://hexdocs.pm/elixir contains the popover code, links to
https://hexdocs.pm/elixir(...)
will trigger appropriate popovers.4. Security
Incoming data is always displayed as plain text to guard against potential malicious payload.
5. Switching
on
andoff
Tooltips can be disabled with the link at the bottom of the page. Same as with Night Mode, user's choice is stored in localStorage.
6. Delay
Popovers will appear after a short delay. This way they won't get trigger on accident (ie. while scrilling the page or just moving cursor around).
7. How it's implemented
Script is based on José's suggestion to use an iframe to display the popover content.
I've started with a basic iframe displaying a simplified version of the requested page. That worked great for smaller, simpler functions. Longer function names/signatures were overflowing and iframe resizing was needed. In addition iframe content was sometimes "jumping" even after the page was fully loaded (I suspected some other JS scripts adding styles and causing content to shift).
At this point I was already sending messages (containing size measurements and load progress info) from the iframe to the parent page - I've decided to try extracting tooltip title and description using JS and sending them to the parent via postMessage.
This is how it works right now: